Add useRequests(): queue rows as React hooks, cached per client - #76

Why

The app keeps its own copy of getRequests() to show upload rows, in a hook it wrote. That copy has two gaps. Native sends no event when it forgets a row after the ack, and no event when cancel() removes a settled row. The app patches the second gap by wrapping cancel(). The first gap stays: a completed row can stay on screen after native forgot it.

The library sends the acks and the cancels itself, so it can close both gaps. This PR moves the hook into the library. The app then creates requests and handles outcomes, and keeps no copy of the queue.

This is display only. It does not change what is sent, acknowledged, or cancelled.

API

On each client:

• useRequests(filter?) returns the rows. It re-renders when a row appears, changes state, or goes. It does not re-render on progress.
• useRequestsWithProgress(filter?) returns the same rows with the bytes of each progress event. It also re-renders on progress.
• filter is { key?, id?, includeCancelled? }. Cancelled rows are left out unless includeCancelled is true. The app hides them today, and a cancelled row has no work left.
• addRequestsListener(listener) returns { remove }. It calls listener with the rows when they change. There is no call when it registers. It is for code outside React, such as a store or a logger.
• getCachedRequests(filter?) returns the rows the hooks see. While nothing listens, it reads native on each call. A result filtered by key or id is a new array each call, so it is not a hook snapshot.
• Completed rows are included until their outcome is acknowledged. The README says not to treat them as work still to do.

On each definition, define() now also returns useRequests(filter?) and useRequestsWithProgress(filter?). They return that key's rows with vars typed as the definition's vars. The filter has no key.

Results keep the same array while the rows they hold are the same, also when the filter is a new object each render. A hook filtered by id looks its row up in an index shared by all hooks, and re-renders only when that row changes. Hooks without an id share one filtered array per key.

The README tells apps to take the hooks out first (const { useRequests } = uploads). The hooks lint rule does not check uploads.useRequests(), because it checks X.useY() only when X starts with a capital letter.

How the cache works

• The client reads native when the first hook or listener subscribes, also when a render read it just before. Native emits from its own thread, so an event can reach no listener between the two.
• Each state event replaces the row it carries. Other rows keep their objects.
• When the ack of a completed or cancelled outcome resolves, the row goes. If the row has moved on, for example a cancelled entry that a same-id mutate() reopened, the client asks native for that row. src/delivery.ts calls a new onAcked after a successful ack. A throw there is a warning only.
• When cancel(id) resolves on a settled row, the row goes. A live row waits for its cancelled event and its ack.
• An error row stays until cancel() or a same-id mutate(). Native sends a state event for a same-id mutate(), so that needs nothing extra. I checked this in the iOS and Android code.
• iOS can settle a live row during an ack with no event. After the ack of an error outcome, the client reads that row from native if it does not show it as an error.
• A state row with reason: 'unhandled-key' is built from the outcome, not the entry. The client reads that row from native instead.
• Native progress is listened to only while a progress hook is mounted.
• The cache's state and progress handlers catch their own errors and send them to onWarning, so they cannot stop the app's other listeners.
• With nothing listening, an ack or a cancel() drops the cached rows instead of patching them. No native read runs in the delivery lane while the journal drains at launch.
• When the last listener leaves, the rows stay. The next subscribe checks them against native.
• A failed native read keeps the rows and sends a warning to onWarning.

A late state event no longer brings back a finished row. Android emits a run's outcome before its last state event, so the ack could remove the row and the late event then added it back. The cache now remembers the ids it removed because native forgot them, at most 256, and checks a later state event for one of those ids against native. After cancel(), the cache keeps a cancelled row until native forgets it.

What to look at

• src/requests.ts: the cache, the filter selector, and the hook.
• src/index.ts: the wiring, the cancel() change, and the define() wrapper.
• src/delivery.ts: onAcked.
• src/testing.ts: settle() now resolves one promise turn later, after the client has handled the ack. A test that awaits settle() then sees the row gone. This depends on delivery's ack() handling the ack in the turn after ackEvents() resolves; comments in both places say so. A macrotask would remove that dependency, but it would make settle() wait on timers, which Jest fake timers hold.
• Defined and UploadClient gained required members. A hand-built test double of either type must add them. The CHANGELOG says so.
• example/RNBGUExample/jest.config.js: maps react to the example's copy. Without it, src/ and react-test-renderer load two Reacts.

Tests

• yarn lint:ci: passes.
• yarn typecheck: passes, with new type tests in src/__typetests__/requests.ts.
• yarn test: 282 tests pass. 67 are new: 62 in src/__tests__/requests.test.ts and 5 in delivery.test.ts. They include an event lost between a render read and the subscribe, a listener that calls cancel() and getRequests() while a row drops, and a count that shows an id lookup does not walk the rows.
• Example app Jest: 13 tests pass. 9 are new in __tests__/useRequests.test.tsx. They render the hooks with react-test-renderer over the fake native, including under StrictMode and with a filter that changes.
• Benchmark with 300 rows, 200 id-filtered hooks and 5 unfiltered hooks: each event now reads 600 rows (one index build and one shared filter) instead of about 61,500. A state event takes 0.10 ms instead of 0.80 ms. Render counts are the same.

Merge order

PR #67 (dylan/deliver-late-definitions) also changes src/delivery.ts. Whichever of the two lands second merges master in.

🤖 Generated with Claude Code